BUILDER R Functions

builder()

The builder() function call the BUILDER software from R. It prepares and passes all input tables and variables to the BUIDLER executable and returns the builder table to R.

The functions neighbours(), seeds(), and catchments(), which generate the input tables required by BUILDER, must be executed before running BUILDER. To access the complete set of output tables, users need to specify a valid output directory using the out_dir parameter. When provided, all input and output tables will be saved to that directory. The main output table — listing conservation area names and their associated catchments — is named “*_COLUMN_All_Unique_BAs.csv” and is also returned to the R session.

Specifying an output directory is especially useful when looping through multiple BUILDER runs, allowing easy comparison of outputs across scenarios. If no output directory is provided, a temporary folder will be used and automatically deleted upon function completion.

While BUILDER generates some hydrology and summary information, we recommend using dedicated functions from the Hydrology category to compute detailed hydrology metrics (see Articles/Assess Hydrology on Reserves for an example). Specifying an output directory also ensures access to the full set of BUILDER output tables.

Usage

builder(
  catchments_sf, 
  data_source = "catchment",
  seeds, 
  reserve_name,
  neighbours, 
  out_dir = NULL,
  builder_local_path, 
  catchment_level_intactness = 1, 
  conservation_area_intactness = 1, 
  area_target_proportion = 1, 
  area_type = "land", 
  construct_conservation_areas = TRUE,  
  area_target_multiplier = 1,
  handle_isolated_catchments = TRUE, 
  output_upstream = FALSE, 
  output_downstream = FALSE, 
  output_hydrology_metrics = FALSE,
  area_land = "Area_Land", 
  area_water = "Area_Water",
  skeluid = "SKELUID", 
  catchnum = "CATCHNUM", 
  subzone = "FDA", 
  zone = "MDA", 
  basin = "BASIN", 
  order1 = "ORDER1",
  order2 = "ORDER2", 
  order3 = "ORDER3", 
  stream_length = "STRMLEN", 
  intactness = "intact", 
  isolated = "Isolated",
  unique_identifier = "PB", 
  handler_summary = FALSE, 
  summary_intactness_props = '""', 
  summary_area_target_props = '""'
)

Arguments

  • catchments_sf: sf object of the catchments dataset with unique identifier column CATCHNUM.
  • data_source: Specify the seed type (catchment or reserve). Default is catchment.
  • seeds: Seeds table from seeds() listing seed catchments and area targets.
  • reserve_name: Reserve column listing the name of the reserve. Only used if data_source Reserve is selected.
  • neighbours: Neighbours table from neighbours() listing all neighbouring pairs of catchments.
  • out_dir: If provided, input (seeds, neighbours and catchments) files and output BUILDER tables will be saved to this directory. Otherwise a temp directory will be used. Function will attempt to create the directory if it doesn’t already exist.
  • builder_local_path: Directory path to the benchmarkbuilder executable.
  • catchment_level_intactness: Minimum intactness value for catchment inclusion (between 0-1). i.e. if value of 1 is used, only 100% intact catchments will be used. Default is 1.
  • conservation_area_intactness: Minimum area-weighted intactness of final conservation areas. Only conservation areas meeting this value will be returned. Default is 1.
  • area_target_proportion: The proportion of the Area target that conservation areas need to meet (0-1) to be returned by the function. Default is 1.
  • area_type: If ‘land’, only terrestrial areas are counted towards the area target. If ‘water’, only water areas are counter. If ‘landwater’, all areas are counted. Default is ‘land’.
  • construct_conservation_areas: Should builder build conservation areas? Default is TRUE.
  • area_target_multiplier: Multiplier applied to the area target in the seed list that allows for adjustments to the area target without having to remake the seeds table. Default is 1.
  • handle_isolated_catchments: Should small isolated catchments be merged into the conservation areas? Default is TRUE.
  • output_upstream: Should upstream catchments be calculated? Default is FALSE.
  • output_downstream: Should downstream catchments be calculated? Default is FALSE.
  • output_hydrology_metrics: Should hydrology metrics be calculated? Default is FALSE.
  • area_land: Catchments column listing the area of land in each catchment. Default is ‘Area_Land’.
  • area_water: Catchments column listing the area of water in each catchment. Default is ‘Area_Water’.
  • skeluid: Catchments column listing the skeluid field. Default is ‘SKELUID’
  • catchnum: Catchments column listing the unique catchments ID. Default is ‘CATCHNUM’
  • subzone: Catchments column listing the hydrological subzone. Default is ‘FDA’
  • zone: Catchments column listing the hydrological zone. Default is ‘MDA’
  • basin: Catchments column listing the basin field. Default is ‘BASIN’
  • order1: Catchments column listing the order 1 field. Default is ‘ORDER1’
  • order2: Catchments column listing the order 2 field. Default is ‘ORDER2’
  • order3: Catchments column listing the order 3 field. Default is ‘ORDER3’
  • stream_length: Catchments column listing stream length. Default is ‘STRMLEN’
  • intactness: Catchments column listing the intactness value. Default is ‘intact’
  • isolated: Catchments column identifying catchments isolated from the stream network. Default is ‘Isolated’
  • unique_identifier: Prefix for conservation area names. Default is ‘PB’
  • handler_summary: Should a summary listing counts of available conservation areas at different intactness and area target proportions be created? Default is FALSE
  • summary_intactness_props: If a summary is created, provide the intactness proportions to be summarised in the format ‘0.7,0.8,0.9’.
  • summary_area_target_props: If a summary is created, provide the area target proportions to be summarised in the format ‘0.7,0.8,0.9’.

📤 Output

A tibble with column names representing conservation areas, and rows of catchments making up the conservation areas. If output_dir is provided, additional BUILDER output tables (e.g., hydrology, summary metrics) are saved. If an out_dir is specified, the returned tibble corresponds to the output file named *_COLUMN_All_Unique_BAs.csv generated for the specific run.

Examples

Running the examples

** Prior to run the example, the benchmarkbuilder executable needs to be acquired by contacting the BEACONs Project.

  1. Download and unzip BEACONs R Tools

  2. Run BUILDER

The main parameters to adjust when building conservation areas are: - data_source: Is the provided seed list catchment or reserve? - Area target: Set in the seeds table, this defines the minimum size for each conservation area. - Catchment-level intactness: Only catchments with intactness values greater than this value will be added to the conservation area. - Conservation area intactness: Only conservation areas with an area-weighted intactness greater than or equal to this value will be returned. - Area-target proportion: The proportion of the Area target that conservation areas need to meet. Allows output of conservation areas smaller than the area target (e.g. if no conservation areas meet 100% of the area target, area target multiplier can be lowered to 0.9 to search for smaller conservation areas).

  • Running ‘builder()’ using catchments seed type.
library(sf)
library(dplyr)
library(tidyr)

########################
##    PARAMS   
########################
# Folder path to unzipped BEACONs_R_Tools folder
dirpath <- "path/to/BEACONs_R_tools"

# Folder path to the benchmarkbuilder executable
builder_path <- "path/to/builderexecutable/folder"

setwd(dirpath)

########################
##    RUN   
########################
source("./R/builder.R")
source("./R/utils")

# Create the folder structure
if (!dir.exists(file.path(dirpath, "Builder_output"))) {
  dir.create(file.path(dirpath, "Builder_output"))
}

# Use all catchments as seeds with a single area target
catchments <- st_read("./data/catchments_sample.shp")

nghbrs <- neighbours(catchments)
seed <- seeds(catchments_sf = catchments, areatarget_value = 1000000000)
builder(catchments_sf = catchments, seeds = seed, neighbours = nghbrs, out_dir = file.path(dest_folder, "Builder_output"), builder_local_path = builder_path)
  • Running ‘builder()’ using reserves seed type.
# Load required libraries
library(sf)
library(dplyr)
library(tidyr)

########################
##    PARAMS   
########################
# Folder path to the benchmarkbuilder executable
builder_path <- "path/to/builderexecutable/folder"

# Folder path to unzipped BEACONs_R_Tools folder
dirpath <- "path/to/BEACONs_R_tools"

setwd(dirpath)

########################
##    RUN   
########################
source("./R/builder.R")
source("./R/utils")

# Create the folder structure
if (!dir.exists(file.path(dest_folder, "Builder_output"))) {
  dir.create(file.path(dest_folder, "Builder_output"))
}

# Use conservation areas as reserve seeds
catchments <- st_read("./data/catchments_sample.shp")
conservation_areas <- st_read("./data/reserves_sample.shp")

nghbrs <- neighbours(catchments)
reserve_seed <- reserve_seeds(catchments, CAs_sf=conservation_areas, CAs_id = "reserve", areatarget_value = 10000, joinType = "INTERSECT")
builder(catchments_sf = catchments, data_source = "Reserve", seeds = reserve_seed, reserve_name = "reserve", neighbours = nghbrs, out_dir = file.path(dest_folder, "Builder_output"), builder_local_path = builder_path, catchment_level_intactness = 0.8, conservation_area_intactness = 0.8)